d3plus-shape

d3plus-shape

Fancy SVG shapes for visualizations

Installing

If you use NPM, npm install d3plus-shape. Otherwise, download the latest release. The released bundle supports AMD, CommonJS, and vanilla environments. Create a custom bundle using Rollup or your preferred bundler. You can also load directly from d3plus.org:

<script src="https://d3plus.org/js/d3plus-shape.v0.11.full.min.js"></script>

Getting Started

Let's say you want to draw 2 rectangles with distinct labels and colors. If you structure your data like this:

var data = [
  {text: "Box #1", width: 200, height: 150, x: 100, y: 75, color: "cornflowerblue"},
  {text: "Box #2", width: 150, height: 100, x: 285, y: 100, color: "firebrick"}
];

It can be passed to the rectangle generator like this:

new d3plus.Rect()
  .data(data)
  .fill(function(d) { return d.color; })
  .label(function(d) { return d.text; })
  .render();

It even detects that the blue rectangle should have a dark label and the red rectangle's should be light!

Please note that the x and y positions are relative to the center of the rectangles.

Click here to view this example live on the web.

API Reference

Classes

Image

Area ⇐ Shape

Bar ⇐ Shape

Circle ⇐ Shape

Line ⇐ Shape

Path ⇐ Shape

Rect ⇐ Shape

Shape ⇐ BaseClass

Functions

distance(p1, p2) ⇒ Number

Calculates the pixel distance between two points.

Image

Kind: global class

• Image
  • new Image()
  • .render([callback]) ↩︎
  • .data([data]) ↩︎
  • .duration([ms]) ↩︎
  • .height([value]) ↩︎
  • .id([value]) ↩︎
  • .pointerEvents([value]) ↩︎
  • .select([selector]) ↩︎
  • .url([value]) ↩︎
  • .width([value]) ↩︎
  • .x([value]) ↩︎
  • .y([value]) ↩︎

new Image()

Creates SVG images based on an array of data.

Example (a sample row of data)

var data = {"url": "file.png", "width": "100", "height": "50"};

Example (passed to the generator)

new Image().data([data]).render();

Example (creates the following)

<image class="d3plus-Image" opacity="1" href="file.png" width="100" height="50" x="0" y="0"></image>

Example (this is shorthand for the following)

image().data([data])();

Example (which also allows a post-draw callback function)

image().data([data])(function() { alert("draw complete!"); })

Image.render([callback]) ↩︎

Renders the current Image to the page. If a callback is specified, it will be called once the images are done drawing.

Kind: static method of Image
Chainable

Param	Type
[callback]	function

Image.data([data]) ↩︎

If data is specified, sets the data array to the specified array and returns the current class instance. If data is not specified, returns the current data array. An tag will be drawn for each object in the array.

Kind: static method of Image
Chainable

Param	Type	Default
[data]	Array	[]

Image.duration([ms]) ↩︎

If ms is specified, sets the animation duration to the specified number and returns the current class instance. If ms is not specified, returns the current animation duration.

Kind: static method of Image
Chainable

Param	Type	Default
[ms]	Number	600

Image.height([value]) ↩︎

If value is specified, sets the height accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current height accessor.

Kind: static method of Image
Chainable

Param	Type
[value]	function | Number

Example

function(d) {
  return d.height;
}

Image.id([value]) ↩︎

If value is specified, sets the id accessor to the specified function and returns the current class instance. If value is not specified, returns the current id accessor. This is useful if you want to duplicate the same image.

Kind: static method of Image
Chainable

Param	Type
[value]	function

Example

function(d) {
  return d.id;
}

Image.pointerEvents([value]) ↩︎

If value is specified, sets the pointer-events accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current pointer-events accessor.

Kind: static method of Image
Chainable

Param	Type	Default
[value]	function | String	"auto"

Image.select([selector]) ↩︎

If selector is specified, sets the SVG container element to the specified d3 selector or DOM element and returns the current class instance. If selector is not specified, returns the current SVG container element.

Kind: static method of Image
Chainable

Param	Type	Default
[selector]	String | HTMLElement	d3.select("body").append("svg")

Image.url([value]) ↩︎

If value is specified, sets the URL accessor to the specified function and returns the current class instance. If value is not specified, returns the current URL accessor.

Kind: static method of Image
Chainable

Param	Type
[value]	function

Example

function(d) {
  return d.url;
}

Image.width([value]) ↩︎

If value is specified, sets the width accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current width accessor.

Kind: static method of Image
Chainable

Param	Type
[value]	function | Number

Example

function(d) {
  return d.width;
}

Image.x([value]) ↩︎

If value is specified, sets the x accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current x accessor.

Kind: static method of Image
Chainable

Param	Type
[value]	function | Number

Example

function(d) {
  return d.x || 0;
}

Image.y([value]) ↩︎

If value is specified, sets the y accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current y accessor.

Kind: static method of Image
Chainable

Param	Type
[value]	function | Number

Example

function(d) {
  return d.y || 0;
}

Area ⇐ Shape

Kind: global class
Extends: Shape

• Area ⇐ Shape
  • new Area()
  • .render([callback]) ↩︎
  • .curve([value]) ↩︎
  • .defined([value]) ↩︎
  • .x0([value]) ↩︎
  • .x1([value]) ↩︎
  • .y0([value]) ↩︎
  • .y1([value]) ↩︎

new Area()

Creates SVG areas based on an array of data.

Area.render([callback]) ↩︎

Draws the area polygons.

Kind: static method of Area
Chainable

Param	Type
[callback]	function

Area.curve([value]) ↩︎

If value is specified, sets the area curve to the specified string and returns the current class instance. If value is not specified, returns the current area curve.

Kind: static method of Area
Chainable

Param	Type	Default
[value]	String	"linear"

Area.defined([value]) ↩︎

If value is specified, sets the defined accessor to the specified function and returns the current class instance. If value is not specified, returns the current defined accessor.

Kind: static method of Area
Chainable

Param	Type
[value]	function

Area.x0([value]) ↩︎

If value is specified, sets the x0 accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current x0 accessor.

Kind: static method of Area
Chainable

Param	Type
[value]	function | Number

Area.x1([value]) ↩︎

If value is specified, sets the x1 accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current x1 accessor.

Kind: static method of Area
Chainable

Param	Type
[value]	function | Number | null

Area.y0([value]) ↩︎

If value is specified, sets the y0 accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current y0 accessor.

Kind: static method of Area
Chainable

Param	Type
[value]	function | Number

Area.y1([value]) ↩︎

If value is specified, sets the y1 accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current y1 accessor.

Kind: static method of Area
Chainable

Param	Type
[value]	function | Number | null

Bar ⇐ Shape

Kind: global class
Extends: Shape

• Bar ⇐ Shape
  • new Bar()
  • .render([callback]) ↩︎
  • .height([value]) ↩︎
  • .width([value]) ↩︎
  • .x0([value]) ↩︎
  • .x1([value]) ↩︎
  • .y0([value]) ↩︎
  • .y1([value]) ↩︎

new Bar()

Creates SVG areas based on an array of data.

Bar.render([callback]) ↩︎

Draws the bars.

Kind: static method of Bar
Chainable

Param	Type
[callback]	function

Bar.height([value]) ↩︎

If value is specified, sets the height accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current height accessor.

Kind: static method of Bar
Chainable

Param	Type
[value]	function | Number

Example

function(d) {
  return d.height;
}

Bar.width([value]) ↩︎

If value is specified, sets the width accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current width accessor.

Kind: static method of Bar
Chainable

Param	Type
[value]	function | Number

Example

function(d) {
  return d.width;
}

Bar.x0([value]) ↩︎

If value is specified, sets the x0 accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current x0 accessor.

Kind: static method of Bar
Chainable

Param	Type
[value]	function | Number

Bar.x1([value]) ↩︎

If value is specified, sets the x1 accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current x1 accessor.

Kind: static method of Bar
Chainable

Param	Type
[value]	function | Number | null

Bar.y0([value]) ↩︎

If value is specified, sets the y0 accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current y0 accessor.

Kind: static method of Bar
Chainable

Param	Type
[value]	function | Number

Bar.y1([value]) ↩︎

If value is specified, sets the y1 accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current y1 accessor.

Kind: static method of Bar
Chainable

Param	Type
[value]	function | Number | null

Circle ⇐ Shape

Kind: global class
Extends: Shape

• Circle ⇐ Shape
  • new Circle()
  • .render([callback]) ↩︎
  • .r([value]) ↩︎

new Circle()

Creates SVG circles based on an array of data.

Circle.render([callback]) ↩︎

Draws the circles.

Kind: static method of Circle
Chainable

Param	Type
[callback]	function

Circle.r([value]) ↩︎

If value is specified, sets the radius accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current radius accessor.

Kind: static method of Circle
Chainable

Param	Type
[value]	function | Number

Example

function(d) {
  return d.r;
}

Line ⇐ Shape

Kind: global class
Extends: Shape

• Line ⇐ Shape
  • new Line()
  • .render([callback]) ↩︎
  • .curve([value]) ↩︎
  • .defined([value]) ↩︎

new Line()

Creates SVG lines based on an array of data.

Line.render([callback]) ↩︎

Draws the lines.

Kind: static method of Line
Chainable

Param	Type
[callback]	function

Line.curve([value]) ↩︎

If value is specified, sets the line curve to the specified string and returns the current class instance. If value is not specified, returns the current line curve.

Kind: static method of Line
Chainable

Param	Type	Default
[value]	String	"linear"

Line.defined([value]) ↩︎

If value is specified, sets the defined accessor to the specified function and returns the current class instance. If value is not specified, returns the current defined accessor.

Kind: static method of Line
Chainable

Param	Type
[value]	function

Path ⇐ Shape

Kind: global class
Extends: Shape

• Path ⇐ Shape
  • new Path()
  • .render([callback]) ↩︎
  • .d([value]) ↩︎

new Path()

Creates SVG rectangles based on an array of data. See this example for help getting started using the rectangle generator.

Path.render([callback]) ↩︎

Draws the paths.

Kind: static method of Path
Chainable

Param	Type
[callback]	function

Path.d([value]) ↩︎

If value is specified, sets the "d" attribute accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current "d" attribute accessor.

Kind: static method of Path
Chainable

Param	Type
[value]	function | String

Example

function(d) {
  return d.path;
}

Rect ⇐ Shape

Kind: global class
Extends: Shape

• Rect ⇐ Shape
  • new Rect()
  • .render([callback]) ↩︎
  • .height([value]) ↩︎
  • .width([value]) ↩︎

new Rect()

Creates SVG rectangles based on an array of data. See this example for help getting started using the rectangle generator.

Rect.render([callback]) ↩︎

Draws the rectangles.

Kind: static method of Rect
Chainable

Param	Type
[callback]	function

Rect.height([value]) ↩︎

If value is specified, sets the height accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current height accessor.

Kind: static method of Rect
Chainable

Param	Type
[value]	function | Number

Example

function(d) {
  return d.height;
}

Rect.width([value]) ↩︎

If value is specified, sets the width accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current width accessor.

Kind: static method of Rect
Chainable

Param	Type
[value]	function | Number

Example

function(d) {
  return d.width;
}

Shape ⇐ BaseClass

Kind: global class
Extends: BaseClass

• Shape ⇐ BaseClass
  • new Shape()
  • .render([callback]) ↩︎
  • .active([value]) ↩︎
  • .activeOpacity([value]) ↩︎
  • .backgroundImage([value]) ↩︎
  • .data([data]) ↩︎
  • .duration([ms]) ↩︎
  • .fill([value]) ↩︎
  • .fontColor([value]) ↩︎
  • .fontFamily([value]) ↩︎
  • .fontResize([value]) ↩︎
  • .fontSize([value]) ↩︎
  • .hover([value]) ↩︎
  • .hoverOpacity([value]) ↩︎
  • .hitArea([bounds]) ↩︎
  • .id([value]) ↩︎
  • .label([value]) ↩︎
  • .labelBounds([bounds]) ↩︎
  • .labelPadding([value]) ↩︎
  • .lineHeight([value]) ↩︎
  • .opacity([value]) ↩︎
  • .scale([value]) ↩︎
  • .select([selector]) ↩︎
  • .shapeRendering([value]) ↩︎
  • .sort([value]) ↩︎
  • .stroke([value]) ↩︎
  • .strokeWidth([value]) ↩︎
  • .textAnchor([value]) ↩︎
  • .vectorEffect([value]) ↩︎
  • .verticalAlign([value]) ↩︎
  • .x([value]) ↩︎
  • .y([value]) ↩︎

new Shape()

An abstracted class for generating shapes.

Shape.render([callback]) ↩︎

Renders the current Shape to the page. If a callback is specified, it will be called once the shapes are done drawing.

Kind: static method of Shape
Chainable

Param	Type
[callback]	function

Shape.active([value]) ↩︎

If value is specified, sets the highlight accessor to the specified function and returns the current class instance. If value is not specified, returns the current highlight accessor.

Kind: static method of Shape
Chainable

Param	Type
[value]	function

Shape.activeOpacity([value]) ↩︎

If value is specified, sets the active opacity to the specified function and returns the current class instance. If value is not specified, returns the current active opacity.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	Number	0.75

Shape.backgroundImage([value]) ↩︎

If value is specified, sets the background-image accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current background-image accessor.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	function | String	false

Shape.data([data]) ↩︎

If data is specified, sets the data array to the specified array and returns the current class instance. If data is not specified, returns the current data array. A shape will be drawn for each object in the array.

Kind: static method of Shape
Chainable

Param	Type	Default
[data]	Array	[]

Shape.duration([ms]) ↩︎

If ms is specified, sets the animation duration to the specified number and returns the current class instance. If ms is not specified, returns the current animation duration.

Kind: static method of Shape
Chainable

Param	Type	Default
[ms]	Number	600

Shape.fill([value]) ↩︎

If value is specified, sets the fill accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current fill accessor.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	function | String	"black"

Shape.fontColor([value]) ↩︎

If value is specified, sets the font-color accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current font-color accessor, which by default returns a color that contrasts the fill color. If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape
Chainable

Param	Type
[value]	function | String | Array

Shape.fontFamily([value]) ↩︎

If value is specified, sets the font-family accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current font-family accessor. If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	function | String | Array	"Verdana"

Shape.fontResize([value]) ↩︎

If value is specified, sets the font resizing accessor to the specified function or boolean and returns the current class instance. If value is not specified, returns the current font resizing accessor. When font resizing is enabled, the font-size of the value returned by label will be resized the best fit the shape. If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape
Chainable

Param	Type
[value]	function | Boolean | Array

Shape.fontSize([value]) ↩︎

If value is specified, sets the font-size accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current font-size accessor. If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	function | String | Array	12

Shape.hover([value]) ↩︎

If value is specified, sets the highlight accessor to the specified function and returns the current class instance. If value is not specified, returns the current highlight accessor.

Kind: static method of Shape
Chainable

Param	Type
[value]	function

Shape.hoverOpacity([value]) ↩︎

If value is specified, sets the hover opacity to the specified function and returns the current class instance. If value is not specified, returns the current hover opacity.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	Number	0.5

Shape.hitArea([bounds]) ↩︎

If bounds is specified, sets the mouse hit area to the specified function and returns the current class instance. If bounds is not specified, returns the current mouse hit area accessor.

Kind: static method of Shape
Chainable

Param	Type	Description
[bounds]	function	The given function is passed the data point, index, and internally defined properties of the shape and should return an object containing the following values: width, height, x, y.

Example

function(d, i, shape) {
  return {
    "width": shape.width,
    "height": shape.height,
    "x": -shape.width / 2,
    "y": -shape.height / 2
  };
}

Shape.id([value]) ↩︎

If value is specified, sets the id accessor to the specified function and returns the current class instance. If value is not specified, returns the current id accessor.

Kind: static method of Shape
Chainable

Param	Type
[value]	function

Shape.label([value]) ↩︎

If value is specified, sets the label accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current text accessor, which is undefined by default. If an array is passed or returned from the function, each value will be rendered as an individual label.

Kind: static method of Shape
Chainable

Param	Type
[value]	function | String | Array

Shape.labelBounds([bounds]) ↩︎

If bounds is specified, sets the label bounds to the specified function and returns the current class instance. If bounds is not specified, returns the current inner bounds accessor.

Kind: static method of Shape
Chainable

Param	Type	Description
[bounds]	function	The given function is passed the data point, index, and internally defined properties of the shape and should return an object containing the following values: width, height, x, y. If an array is returned from the function, each value will be used in conjunction with each label.

Example

function(d, i, shape) {
  return {
    "width": shape.width,
    "height": shape.height,
    "x": -shape.width / 2,
    "y": -shape.height / 2
  };
}

Shape.labelPadding([value]) ↩︎

If value is specified, sets the label padding to the specified number and returns the current class instance. If value is not specified, returns the current label padding. If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	function | Number | Array	10

Shape.lineHeight([value]) ↩︎

If value is specified, sets the line-height accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current line-height accessor. If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape
Chainable

Param	Type
[value]	function | String | Array

Shape.opacity([value]) ↩︎

If value is specified, sets the opacity accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current opacity accessor.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	Number	1

Shape.scale([value]) ↩︎

If value is specified, sets the scale accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current scale accessor.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	function | Number	1

Shape.select([selector]) ↩︎

If selector is specified, sets the SVG container element to the specified d3 selector or DOM element and returns the current class instance. If selector is not specified, returns the current SVG container element.

Kind: static method of Shape
Chainable

Param	Type	Default
[selector]	String | HTMLElement	d3.select("body").append("svg")

Shape.shapeRendering([value]) ↩︎

If value is specified, sets the shape-rendering accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current shape-rendering accessor.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	function | String	"geometricPrecision"

Example

function(d) {
  return d.x;
}

Shape.sort([value]) ↩︎

If value is specified, sets the sort comparator to the specified function and returns the current class instance. If value is not specified, returns the current sort comparator.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	false | function	[]

Shape.stroke([value]) ↩︎

If value is specified, sets the stroke accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current stroke accessor.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	function | String	"black"

Shape.strokeWidth([value]) ↩︎

If value is specified, sets the stroke-width accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current stroke-width accessor.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	function | Number	0

Shape.textAnchor([value]) ↩︎

If value is specified, sets the text-anchor accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current text-anchor accessor, which is "start" by default. Accepted values are "start", "middle", and "end". If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	function | String | Array	"start"

Shape.vectorEffect([value]) ↩︎

If value is specified, sets the vector-effect accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current vector-effect accessor.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	function | String	"non-scaling-stroke"

Shape.verticalAlign([value]) ↩︎

If value is specified, sets the vertical alignment accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current vertical alignment accessor, which is "top" by default. Accepted values are "top", "middle", and "bottom". If an array is passed or returned from the function, each value will be used in conjunction with each label.

Kind: static method of Shape
Chainable

Param	Type	Default
[value]	function | String | Array	"start"

Shape.x([value]) ↩︎

If value is specified, sets the x accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current x accessor.

Kind: static method of Shape
Chainable

Param	Type
[value]	function | Number

Example

function(d) {
  return d.x;
}

Shape.y([value]) ↩︎

If value is specified, sets the y accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current y accessor.

Kind: static method of Shape
Chainable

Param	Type
[value]	function | Number

Example

function(d) {
  return d.y;
}

distance(p1, p2) ⇒ Number

Calculates the pixel distance between two points.

Kind: global function

Param	Type	Description
p1	Array | Object	The first point, either an Array formatted like [x, y] or a keyed object formatted like {x, y}.
p2	Array | Object	The second point, either an Array formatted like [x, y] or a keyed object formatted like {x, y}

_{Documentation generated on Mon, 19 Dec 2016 20:49:08 GMT}